﻿<html>
  <head>
    <meta name="generator" content="h-smile:richtext"/>
  </head>
<body>
  <h1>Implementation of <a href="http://promises-aplus.github.io/promises-spec">Promises/A+ specification</a></h1>
  <h2>The promise() function</h2>
  <p>The <code>promise()</code> function returns callable object(function) that has method <code>.then(onFulfilled, onRejected)</code></p>
  <p>The promise is created either as (<strong>case #1</strong>):</p>
  <pre>var prom = promise();
</pre>
  <p>or as (<strong>case #2</strong>)</p>
  <pre>var prom = promise( function( <em>resolve</em>:function, <em>reject</em>:function ) {...} );
</pre>
  <h3>To fulfill/resolve the promise in case #1</h3>
  <p>call it as <code>prom(</code><u><code>true</code></u><code>, params)</code>. Where the <em>params</em> is an array of values that will be applied to onFulfilled callback functions registered by <code>.then()</code> method.</p>
  <h3>To reject the promise in case #1</h3>
  <p>call it as <code>prom(</code><u><code>false</code></u><code>, params)</code>. Where the <em>params</em> is an array of values that will be applied to onRejected callbacks registered by <code>.then()</code> method.</p>
  <h3>To resolve or reject the promise in case #2</h3>
  <p>Simply call <em>resolve</em>(result) or <em>reject(error)</em> callback functions from your function body.</p>
  <h2>Promise methods</h2>
  <p>The <code>promise()</code> function returns function-object that has the following methods by itself:</p>
  <dl>
    <dt>promise.then</dt>
    <dd><strong>(onFulfilled</strong> : function(data) [, <strong>onRejected</strong>: function(err) ] <strong>)</strong> : <em>promise</em>
      <p>Appends fulfillment and rejection handlers/callbacks to the promise, and returns a new promise. Either one of these handlers will be invoked on promise completion.</p></dd>
    <dt>promise.catch</dt>
    <dd><strong>(onError</strong>: function(err) <strong>)</strong> : <em>promise</em>
      <p>Appends rejection handler to the promise, and returns a new promise.</p></dd>
    <dt>promise.finally</dt>
    <dd><strong>(onResolved</strong>: function(dataOrErr) <strong>)</strong> : <em>promise</em>
      <p>Appends &quot;resolved&quot; handler to the promise, and returns a new promise. This handler will be called on completion of &nbsp;the promise, either successfully or with error.</p></dd>
    <dt>promise.when</dt>
    <dd><strong>( promise1, promise2, promise3, ... )</strong> : <em>promise</em>
      <p>Static method, returns new promise that will be fulfilled when all arguments(promises) will be fullfiled. If either one of promises is rejected it will rejected too.</p></dd></dl>
  <h2>Redefined View/Element.request() functions</h2>
  <p>The <em>promise.tis</em> also redefines the Element.request() method - http get/post/put/delete call. So with this module included the Element.request() can be called in one of three forms:</p>
  <ol>
    <li><strong>element.request(</strong> <strong>callback</strong>: function, <strong>httpcmd </strong>, <strong>url</strong>: string [, <strong>params</strong>: object [, <strong>headers</strong>: object] ] <strong>) </strong>: true | false<br/>- asynchronous request with server response delivered to callback function.</li>
    <li><strong>element.request(</strong> <strong>timeout</strong>: integer, <strong>httpcmd </strong>, <strong>url</strong>: string [, <strong>params</strong>: object [, <strong>headers</strong>: object] ] <strong>) </strong>: (data, status)<br/>- synchronous request with server response delivered as first return value and http status code as second.</li>
    <li><strong>element.request(</strong> <strong>httpcmd </strong>, <strong>url</strong>: string [, <strong>params</strong>: object [, <strong>headers</strong>: object] ] <strong>) </strong>: <strong>promise</strong>,<br/>- asynchronous request, server response is delivered to the onsuccess callback registered by <code>.then(onsuccess,onfailure)</code> call of the promise.</li>
    <li><strong>view.request(</strong> <strong>params</strong>: map &nbsp;<strong>) </strong>: <strong>promise</strong>,<br/>- asynchronous request, server response is delivered to the onsuccess callback registered by <code>.then(onsuccess,onfailure)</code> call of the promise.</li></ol>
  <h2>promise() and await</h2>
  <p><code>await</code> operator allows to awoid using callbacks with promises and write asynchronous logic in linear fashion:</p>
  <pre>async function getRemoteTexts(url)
{
  try {
    var text = <u>await</u> view.request { url: url, output: #string };
    stdout.println(&quot;complete:&quot;, text);
  } catch(e) {
    stdout.println(&quot;got error:&quot;, e);
  }
}
// starting the task:
getRemoteTexts(&quot;http://sciter.com/test/text.txt&quot;);
stdout.println(&quot;task started&quot;);
</pre>
  <p>When you will run this code snippet in Sciter you will see following output in console:</p>
  <pre>&gt; task started
&gt; complete: {content of test/text.txt file }
</pre>
  <p>&quot;&gt; task started&quot; will appear first as any function that contains <em>await</em> inside gets automatically converted to Task function. &nbsp;</p>
  <p>Invocation of Task function competes immediately and body of the function gets queued for future execution.</p>
  <p>When execution hits <em>await</em> statement the task gets postponed until <em>view.request</em> completion (promise resolving).</p>
  <p>In other words: await is the way of waiting for promise to be resolved.</p>
</body>
</html>